Edit credentials summary similar to spec #39569
Conversation
Spec: > Credentials are HTTP cookies, TLS client certificates, and authentication entries (for HTTP authentication).
|
Preview URLs (comment last updated: 2025-05-20 23:03:55) |
Co-authored-by: wbamberg <will@bootbonnet.ca>
| @@ -205,9 +205,13 @@ See the reference documentation for {{domxref("RequestInit", "", "mode")}} for m | |||
|
|
|||
| ### Including credentials | |||
|
|
|||
| Credentials are cookies, {{glossary("TLS")}} client certificates, or authentication headers containing a username and password. | |||
| In the context of an HTTP request, a credential is an extra piece of data sent along with the request, that the server may use to authenticate the user. All the following items are considered to be credentials: | |||
There was a problem hiding this comment.
@wbamberg This is a huge improvement. I also think the definitive guide should be in this file because it's easy to digest and has a high likelihood of being applicable to your first usage.
I had some edits to suggest, but I'm mostly interested in your thoughts about this one:
| In the context of an HTTP request, a credential is an extra piece of data sent along with the request, that the server may use to authenticate the user. All the following items are considered to be credentials: | |
| In the context of a `fetch` request, a credential is an extra piece of data sent along with the request that the server may use to authenticate the user. All the following items are considered to be credentials: |
I'm assuming that this definition is specific to the fetch API, not all of HTTP. e.g., a curl command with a credentials header wouldn't behave the way this section describes, would it?
There was a problem hiding this comment.
Sure, I'm happy with this, although "fetch" here should not get code formatting because it isn't an identifier in this context.
There was a problem hiding this comment.
@wbamberg I'm not sure what you mean by "an identifier in the context." Perhaps you could word it a different way?
FWIW, the reason I used code formatting was to emphasize it applies to the fetch API, not HTTP in general, and I think the word "fetch" is used colloquially to mean, "A client initiates a call to a server." I didn't want a reader to mistakenly interpret it that way.
There was a problem hiding this comment.
I mean, there's no code entity which we'd refer to as fetch. There's a fetch() method, and we would use code formatting it we wanted to say something like "When you call fetch()...". When we talk about "the fetch API" we're talking about an abstraction. In the rest of this guide, and in the overview page, we actually capitalize it, like "the Fetch API".
If you wanted, you could say "In the context of the Fetch API, ...".
| - {{glossary("TLS")}} client certificates | ||
| - The {{httpheader("Authorization")}} and {{httpheader("Proxy-Authorization")}} headers. | ||
|
|
||
| By default, credentials are only included in same-origin requests. To customize this behavior, as well as to control whether the browser respects any **`Set-Cookie`** response headers, set the [`credentials`](/en-US/docs/Web/API/RequestInit#credentials) option, which can take one of the following three values: |
There was a problem hiding this comment.
I think the Set-Cookie response is handled differently for each of these bullet points. If I'm understanding that correctly, it may make sense to add the specifics in each one.
There was a problem hiding this comment.
I suppose "include credentials in the response" in bullet 1 and "send and include credentials" in bullet 2 are clumsy ways of saying "include the Set-Cookie response header" (since it doesn't make sense to include, say, TLS client certificate in a response). Similarly in the later bullets about "the response, including credentials, will be delivered to the caller".
It would be better to be clear that this is (AFAICT) specifically about Set-Cookie.
It's a very complicated corner of the fetch API, and one that I tried to improve when I rewrote this doc, but there's definitely still room for improvement!
Spec:
Closes #39561